Expand description
This crate lets you display simple markdown snippets or scrollable wrapped markdown texts in the terminal.
In order to use Termimad you typically need
- some markdown: a string which you can have loaded or dynamically built
- a skin: which defines the colors and style attributes of every parts
Additionnaly, you might define an area of the screen in which to draw (and maybe scroll).
The skin
It’s an instance of MadSkin
whose fields you customize according
to your tastes or (better) to your application’s configuration.
use termimad::crossterm::style::{Color::*, Attribute::*};
use termimad::*;
// start with the default skin
let mut skin = MadSkin::default();
// let's decide bold is in light gray
skin.bold.set_fg(gray(20));
// let's make strikeout not striked out but red, with no specific background, and bold
skin.strikeout = CompoundStyle::new(Some(Red), None, Bold.into());
Beware:
- you may define colors in full
rgb
but this will limit compatibility with old terminals. It’s recommended to stick to Ansi colors, gray levels, or Crossterm predefined values. - styles are composed. For example a word may very well be italic, bold and striked out. It might not be wise to have them differ only by their background color for example.
Display a simple inline snippet
// with the default skin, nothing simpler:
termimad::print_inline("value: **52**");
Print a text
A multi-line markdown string can be printed the same way than an inline snippet, but you usually want it to be wrapped according to the available terminal width.
eprintln!("{}", skin.term_text(my_markdown));
MadSkin
contains other functions to prepare a text for no specific size or for one which isn’t the terminal’s width. It also offers several functions to print it either on stdout
or on a given Write
.
Display a text, maybe scroll it
A terminal application often uses an alternate screen instead of just dumping its text to stdout, and you often want to display in a specific rect of that screen, with adequate wrapping and not writing outside that rect.
You may also want to display a scrollbar if the text doesn’t fit the area. A MadView
makes that simple:
let area = Area::new(0, 0, 10, 12);
let mut view = MadView::from(markdown, area, skin);
view.write().unwrap();
If you don’t want to give ownership of the skin, markdown and area, you may prefer to use a TextView
.
You may see how to write a text viewer responding to key inputs to scroll a markdown text in the scrollable example.
Templates
In order to separate the rendering format from the content, the format!
macro is not always a good solution because you may not be sure the content is free of characters which may mess the markdown.
A solution is to use one of the templating functions or macros.
Example:
mad_print_inline!(
&skin,
"**$0 formula:** *$1*", // the markdown template, interpreted once
"Disk", // fills $0
"2*π*r", // fills $1. Note that the stars don't mess the markdown
);
Main difference with using print!(format!( ... ))
:
- the markdown parsing and template building are done only once (using
once_cell
internally) - the given values aren’t interpreted as markdown fragments and don’t impact the style
- arguments can be omited, repeated, given in any order
- no support for fmt parameters or arguments other than
&str
(in the current version)
You’ll find more examples and advice in the templates example.
Examples
The repository contains several other examples, which hopefully cover the whole API while being simple enough. It’s recommended you start by trying them or at least glance at their code.
Re-exports
pub use minimad;
Modules
Macros
$0
to $9
places in the template.$0
to $9
places in the template.Structs
allowed
columns are
written.